/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.aop.aspectj;

import org.aopalliance.aop.Advice;

import org.springframework.aop.Pointcut;
import org.springframework.aop.PointcutAdvisor;
import org.springframework.core.Ordered;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;

/**
 * 这个类在 Spring AOP 中代表一个单独的 Advisor。
 * 每个 Advisor 包含：
 * - Advice：具体的增强逻辑（如前置、后置、环绕通知）
 * - Pointcut：增强逻辑生效的条件（哪些方法被拦截）
 *
 * <p>Example:
 *
 * 例子：
 * @Aspect
 * public class LogAspect {
 *
 *     @Before("execution(* com.example.service.*.*(..))")
 *     public void beforeMethod(JoinPoint joinPoint) {
 *         System.out.println("Before method: " + joinPoint.getSignature().getName());
 *     }
 * }
 *
 * Spring 会为上面这个方法创建一个 AspectJPointcutAdvisor：
 * - Advice：beforeMethod()
 * - Pointcut：execution(* com.example.service.*.*(..))
 *
 * <p>In proxy creation, Spring collects Advisors like this to form the
 * enhancement chain (advice chain). When a method on a proxy is invoked,
 * Spring traverses this chain and executes matching Advice in order.
 *
 * 在代理对象创建过程中，Spring 会收集类似的 Advisors 构成增强链（advice chain）。
 * 当代理方法被调用时，Spring 遍历这个链条，按顺序执行匹配的 Advice。
 *
 * AspectJPointcutAdvisor that adapts an {@link AbstractAspectJAdvice}
 * to the {@link org.springframework.aop.PointcutAdvisor} interface.
 *
 * @author Adrian Colyer
 * @author Juergen Hoeller
 * @since 2.0
 */
public class AspectJPointcutAdvisor implements PointcutAdvisor, Ordered {

	/** The Advice to execute when the Pointcut matches. */
	// 当 Pointcut 匹配方法时要执行的增强逻辑（Advice）
	private final AbstractAspectJAdvice advice;

	/** The Pointcut defining where the advice applies. */
	// 定义增强逻辑生效范围的切入点（Pointcut）
	private final Pointcut pointcut;

	/** Optional order for advisor chain execution. */
	// 可选的执行顺序，决定在增强链中的位置
	@Nullable
	private Integer order;


	/**
	 * Create a new AspectJPointcutAdvisor for the given advice.
	 *
	 * 为指定的 AbstractAspectJAdvice 创建一个 AspectJPointcutAdvisor
	 *
	 * @param advice the AbstractAspectJAdvice to wrap
	 *               要封装的增强逻辑
	 */
	public AspectJPointcutAdvisor(AbstractAspectJAdvice advice) {
		Assert.notNull(advice, "Advice must not be null");
		this.advice = advice;
		// 安全构建切入点
		this.pointcut = advice.buildSafePointcut();
	}


	public void setOrder(int order) {
		this.order = order;
	}

	@Override
	public int getOrder() {
		if (this.order != null) {
			return this.order;
		}
		else {
			return this.advice.getOrder();
		}
	}

	@Override
	public boolean isPerInstance() {
		// 每个目标对象实例独立使用
		return true;
	}

	@Override
	public Advice getAdvice() {
		return this.advice;
	}

	@Override
	public Pointcut getPointcut() {
		return this.pointcut;
	}

	/**
	 * Return the name of the aspect (bean) in which the advice was declared.
	 * 返回声明该 Advice 的切面 Bean 名称
	 *
	 * @since 4.3.15
	 * @see AbstractAspectJAdvice#getAspectName()
	 */
	public String getAspectName() {
		return this.advice.getAspectName();
	}


	@Override
	public boolean equals(@Nullable Object other) {
		if (this == other) {
			return true;
		}
		if (!(other instanceof AspectJPointcutAdvisor)) {
			return false;
		}
		AspectJPointcutAdvisor otherAdvisor = (AspectJPointcutAdvisor) other;
		return this.advice.equals(otherAdvisor.advice);
	}

	@Override
	public int hashCode() {
		return AspectJPointcutAdvisor.class.hashCode() * 29 + this.advice.hashCode();
	}

}
